<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the use of the GNU compilers.

Copyright (C) 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Diagnostic Message Formatting Options (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Invoking-GCC.html" rel="up" title="Invoking GCC">
<link href="Warning-Options.html" rel="next" title="Warning Options">
<link href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html" rel="prev" title="Objective-C and Objective-C++ Dialect Options">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en_US">
<span id="Diagnostic-Message-Formatting-Options"></span><div class="header">
<p>
Next: <a href="Warning-Options.html" accesskey="n" rel="next">Warning Options</a>, Previous: <a href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html" accesskey="p" rel="prev">Objective-C and Objective-C++ Dialect Options</a>, Up: <a href="Invoking-GCC.html" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Options-to-Control-Diagnostic-Messages-Formatting"></span><h3 class="section">3.7 Options to Control Diagnostic Messages Formatting</h3>
<span id="index-options-to-control-diagnostics-formatting"></span>
<span id="index-diagnostic-messages"></span>
<span id="index-message-formatting"></span>

<p>Traditionally, diagnostic messages have been formatted irrespective of
the output device&rsquo;s aspect (e.g. its width, &hellip;).  You can use the
options described below
to control the formatting algorithm for diagnostic messages, 
e.g. how many characters per line, how often source location
information should be reported.  Note that some language front ends may not
honor these options.
</p>
<dl compact="compact">
<dd><span id="index-fmessage_002dlength"></span>
</dd>
<dt><code>-fmessage-length=<var>n</var></code></dt>
<dd><p>Try to format error messages so that they fit on lines of about
<var>n</var> characters.  If <var>n</var> is zero, then no line-wrapping is
done; each error message appears on a single line.  This is the
default for all front ends.
</p>
<p>Note - this option also affects the display of the &lsquo;<samp>#error</samp>&rsquo; and
&lsquo;<samp>#warning</samp>&rsquo; pre-processor directives, and the &lsquo;<samp>deprecated</samp>&rsquo;
function/type/variable attribute.  It does not however affect the
&lsquo;<samp>pragma GCC warning</samp>&rsquo; and &lsquo;<samp>pragma GCC error</samp>&rsquo; pragmas.
</p>
</dd>
<dt><code>-fdiagnostics-plain-output</code></dt>
<dd><p>This option requests that diagnostic output look as plain as possible, which
may be useful when running <code>dejagnu</code> or other utilities that need to
parse diagnostics output and prefer that it remain more stable over time.
<samp>-fdiagnostics-plain-output</samp> is currently equivalent to the following
options:
</p><div class="example">
<pre class="example">-fno-diagnostics-show-caret
-fno-diagnostics-show-line-numbers
-fdiagnostics-color=never
-fdiagnostics-urls=never
-fdiagnostics-path-format=separate-events
</pre></div>
<p>In the future, if GCC changes the default appearance of its diagnostics, the
corresponding option to disable the new behavior will be added to this list.
</p>
<span id="index-fdiagnostics_002dshow_002dlocation"></span>
</dd>
<dt><code>-fdiagnostics-show-location=once</code></dt>
<dd><p>Only meaningful in line-wrapping mode.  Instructs the diagnostic messages
reporter to emit source location information <em>once</em>; that is, in
case the message is too long to fit on a single physical line and has to
be wrapped, the source location won&rsquo;t be emitted (as prefix) again,
over and over, in subsequent continuation lines.  This is the default
behavior.
</p>
</dd>
<dt><code>-fdiagnostics-show-location=every-line</code></dt>
<dd><p>Only meaningful in line-wrapping mode.  Instructs the diagnostic
messages reporter to emit the same source location information (as
prefix) for physical lines that result from the process of breaking
a message which is too long to fit on a single line.
</p>
<span id="index-fdiagnostics_002dcolor"></span>
<span id="index-highlight_002c-color"></span>
<span id="index-GCC_005fCOLORS-environment-variable"></span>
</dd>
<dt><code>-fdiagnostics-color[=<var>WHEN</var>]</code></dt>
<dt><code>-fno-diagnostics-color</code></dt>
<dd><p>Use color in diagnostics.  <var>WHEN</var> is &lsquo;<samp>never</samp>&rsquo;, &lsquo;<samp>always</samp>&rsquo;,
or &lsquo;<samp>auto</samp>&rsquo;.  The default depends on how the compiler has been configured,
it can be any of the above <var>WHEN</var> options or also &lsquo;<samp>never</samp>&rsquo;
if <code>GCC_COLORS</code> environment variable isn&rsquo;t present in the environment,
and &lsquo;<samp>auto</samp>&rsquo; otherwise.
&lsquo;<samp>auto</samp>&rsquo; makes GCC use color only when the standard error is a terminal,
and when not executing in an emacs shell.
The forms <samp>-fdiagnostics-color</samp> and <samp>-fno-diagnostics-color</samp> are
aliases for <samp>-fdiagnostics-color=always</samp> and
<samp>-fdiagnostics-color=never</samp>, respectively.
</p>
<p>The colors are defined by the environment variable <code>GCC_COLORS</code>.
Its value is a colon-separated list of capabilities and Select Graphic
Rendition (SGR) substrings. SGR commands are interpreted by the
terminal or terminal emulator.  (See the section in the documentation
of your text terminal for permitted values and their meanings as
character attributes.)  These substring values are integers in decimal
representation and can be concatenated with semicolons.
Common values to concatenate include
&lsquo;<samp>1</samp>&rsquo; for bold,
&lsquo;<samp>4</samp>&rsquo; for underline,
&lsquo;<samp>5</samp>&rsquo; for blink,
&lsquo;<samp>7</samp>&rsquo; for inverse,
&lsquo;<samp>39</samp>&rsquo; for default foreground color,
&lsquo;<samp>30</samp>&rsquo; to &lsquo;<samp>37</samp>&rsquo; for foreground colors,
&lsquo;<samp>90</samp>&rsquo; to &lsquo;<samp>97</samp>&rsquo; for 16-color mode foreground colors,
&lsquo;<samp>38;5;0</samp>&rsquo; to &lsquo;<samp>38;5;255</samp>&rsquo;
for 88-color and 256-color modes foreground colors,
&lsquo;<samp>49</samp>&rsquo; for default background color,
&lsquo;<samp>40</samp>&rsquo; to &lsquo;<samp>47</samp>&rsquo; for background colors,
&lsquo;<samp>100</samp>&rsquo; to &lsquo;<samp>107</samp>&rsquo; for 16-color mode background colors,
and &lsquo;<samp>48;5;0</samp>&rsquo; to &lsquo;<samp>48;5;255</samp>&rsquo;
for 88-color and 256-color modes background colors.
</p>
<p>The default <code>GCC_COLORS</code> is
</p><div class="example">
<pre class="example">error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:\
quote=01:path=01;36:fixit-insert=32:fixit-delete=31:\
diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32:\
type-diff=01;32:fnname=01;32:targs=35
</pre></div>
<p>where &lsquo;<samp>01;31</samp>&rsquo; is bold red, &lsquo;<samp>01;35</samp>&rsquo; is bold magenta,
&lsquo;<samp>01;36</samp>&rsquo; is bold cyan, &lsquo;<samp>32</samp>&rsquo; is green, &lsquo;<samp>34</samp>&rsquo; is blue,
&lsquo;<samp>01</samp>&rsquo; is bold, and &lsquo;<samp>31</samp>&rsquo; is red.
Setting <code>GCC_COLORS</code> to the empty string disables colors.
Supported capabilities are as follows.
</p>
<dl compact="compact">
<dd><span id="index-error-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>error=</code></dt>
<dd><p>SGR substring for error: markers.
</p>
<span id="index-warning-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>warning=</code></dt>
<dd><p>SGR substring for warning: markers.
</p>
<span id="index-note-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>note=</code></dt>
<dd><p>SGR substring for note: markers.
</p>
<span id="index-path-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>path=</code></dt>
<dd><p>SGR substring for colorizing paths of control-flow events as printed
via <samp>-fdiagnostics-path-format=</samp>, such as the identifiers of
individual events and lines indicating interprocedural calls and returns.
</p>
<span id="index-range1-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>range1=</code></dt>
<dd><p>SGR substring for first additional range.
</p>
<span id="index-range2-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>range2=</code></dt>
<dd><p>SGR substring for second additional range.
</p>
<span id="index-locus-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>locus=</code></dt>
<dd><p>SGR substring for location information, &lsquo;<samp>file:line</samp>&rsquo; or
&lsquo;<samp>file:line:column</samp>&rsquo; etc.
</p>
<span id="index-quote-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>quote=</code></dt>
<dd><p>SGR substring for information printed within quotes.
</p>
<span id="index-fnname-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>fnname=</code></dt>
<dd><p>SGR substring for names of C++ functions.
</p>
<span id="index-targs-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>targs=</code></dt>
<dd><p>SGR substring for C++ function template parameter bindings.
</p>
<span id="index-fixit_002dinsert-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>fixit-insert=</code></dt>
<dd><p>SGR substring for fix-it hints suggesting text to
be inserted or replaced.
</p>
<span id="index-fixit_002ddelete-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>fixit-delete=</code></dt>
<dd><p>SGR substring for fix-it hints suggesting text to
be deleted.
</p>
<span id="index-diff_002dfilename-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>diff-filename=</code></dt>
<dd><p>SGR substring for filename headers within generated patches.
</p>
<span id="index-diff_002dhunk-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>diff-hunk=</code></dt>
<dd><p>SGR substring for the starts of hunks within generated patches.
</p>
<span id="index-diff_002ddelete-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>diff-delete=</code></dt>
<dd><p>SGR substring for deleted lines within generated patches.
</p>
<span id="index-diff_002dinsert-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>diff-insert=</code></dt>
<dd><p>SGR substring for inserted lines within generated patches.
</p>
<span id="index-type_002ddiff-GCC_005fCOLORS-capability"></span>
</dd>
<dt><code>type-diff=</code></dt>
<dd><p>SGR substring for highlighting mismatching types within template
arguments in the C++ frontend.
</p></dd>
</dl>

<span id="index-fdiagnostics_002durls"></span>
<span id="index-urls"></span>
<span id="index-GCC_005fURLS-environment-variable"></span>
<span id="index-TERM_005fURLS-environment-variable"></span>
</dd>
<dt><code>-fdiagnostics-urls[=<var>WHEN</var>]</code></dt>
<dd><p>Use escape sequences to embed URLs in diagnostics.  For example, when
<samp>-fdiagnostics-show-option</samp> emits text showing the command-line
option controlling a diagnostic, embed a URL for documentation of that
option.
</p>
<p><var>WHEN</var> is &lsquo;<samp>never</samp>&rsquo;, &lsquo;<samp>always</samp>&rsquo;, or &lsquo;<samp>auto</samp>&rsquo;.
&lsquo;<samp>auto</samp>&rsquo; makes GCC use URL escape sequences only when the standard error
is a terminal, and when not executing in an emacs shell or any graphical
terminal which is known to be incompatible with this feature, see below.
</p>
<p>The default depends on how the compiler has been configured.
It can be any of the above <var>WHEN</var> options.
</p>
<p>GCC can also be configured (via the
<samp>--with-diagnostics-urls=auto-if-env</samp> configure-time option)
so that the default is affected by environment variables.
Under such a configuration, GCC defaults to using &lsquo;<samp>auto</samp>&rsquo;
if either <code>GCC_URLS</code> or <code>TERM_URLS</code> environment variables are
present and non-empty in the environment of the compiler, or &lsquo;<samp>never</samp>&rsquo;
if neither are.
</p>
<p>However, even with <samp>-fdiagnostics-urls=always</samp> the behavior is
dependent on those environment variables:
If <code>GCC_URLS</code> is set to empty or &lsquo;<samp>no</samp>&rsquo;, do not embed URLs in
diagnostics.  If set to &lsquo;<samp>st</samp>&rsquo;, URLs use ST escape sequences.
If set to &lsquo;<samp>bel</samp>&rsquo;, the default, URLs use BEL escape sequences.
Any other non-empty value enables the feature.
If <code>GCC_URLS</code> is not set, use <code>TERM_URLS</code> as a fallback.
Note: ST is an ANSI escape sequence, string terminator &lsquo;<samp>ESC \</samp>&rsquo;,
BEL is an ASCII character, CTRL-G that usually sounds like a beep.
</p>
<p>At this time GCC tries to detect also a few terminals that are known to
not implement the URL feature, and have bugs or at least had bugs in
some versions that are still in use, where the URL escapes are likely
to misbehave, i.e. print garbage on the screen.
That list is currently xfce4-terminal, certain known to be buggy
gnome-terminal versions, the linux console, and mingw.
This check can be skipped with the <samp>-fdiagnostics-urls=always</samp>.
</p>
<span id="index-fno_002ddiagnostics_002dshow_002doption"></span>
<span id="index-fdiagnostics_002dshow_002doption"></span>
</dd>
<dt><code>-fno-diagnostics-show-option</code></dt>
<dd><p>By default, each diagnostic emitted includes text indicating the
command-line option that directly controls the diagnostic (if such an
option is known to the diagnostic machinery).  Specifying the
<samp>-fno-diagnostics-show-option</samp> flag suppresses that behavior.
</p>
<span id="index-fno_002ddiagnostics_002dshow_002dcaret"></span>
<span id="index-fdiagnostics_002dshow_002dcaret"></span>
</dd>
<dt><code>-fno-diagnostics-show-caret</code></dt>
<dd><p>By default, each diagnostic emitted includes the original source line
and a caret &lsquo;<samp>^</samp>&rsquo; indicating the column.  This option suppresses this
information.  The source line is truncated to <var>n</var> characters, if
the <samp>-fmessage-length=n</samp> option is given.  When the output is done
to the terminal, the width is limited to the width given by the
<code>COLUMNS</code> environment variable or, if not set, to the terminal width.
</p>
<span id="index-fno_002ddiagnostics_002dshow_002dlabels"></span>
<span id="index-fdiagnostics_002dshow_002dlabels"></span>
</dd>
<dt><code>-fno-diagnostics-show-labels</code></dt>
<dd><p>By default, when printing source code (via <samp>-fdiagnostics-show-caret</samp>),
diagnostics can label ranges of source code with pertinent information, such
as the types of expressions:
</p>
<div class="example">
<pre class="example">    printf (&quot;foo %s bar&quot;, long_i + long_j);
                 ~^       ~~~~~~~~~~~~~~~
                  |              |
                  char *         long int
</pre></div>

<p>This option suppresses the printing of these labels (in the example above,
the vertical bars and the &ldquo;char *&rdquo; and &ldquo;long int&rdquo; text).
</p>
<span id="index-fno_002ddiagnostics_002dshow_002dcwe"></span>
<span id="index-fdiagnostics_002dshow_002dcwe"></span>
</dd>
<dt><code>-fno-diagnostics-show-cwe</code></dt>
<dd><p>Diagnostic messages can optionally have an associated
<a href="https://cwe.mitre.org/index.html">CWE</a> identifier.
GCC itself only provides such metadata for some of the <samp>-fanalyzer</samp>
diagnostics.  GCC plugins may also provide diagnostics with such metadata.
By default, if this information is present, it will be printed with
the diagnostic.  This option suppresses the printing of this metadata.
</p>
<span id="index-fno_002ddiagnostics_002dshow_002drules"></span>
<span id="index-fdiagnostics_002dshow_002drules"></span>
</dd>
<dt><code>-fno-diagnostics-show-rules</code></dt>
<dd><p>Diagnostic messages can optionally have rules associated with them, such
as from a coding standard, or a specification.
GCC itself does not do this for any of its diagnostics, but plugins may do so.
By default, if this information is present, it will be printed with
the diagnostic.  This option suppresses the printing of this metadata.
</p>
<span id="index-fno_002ddiagnostics_002dshow_002dline_002dnumbers"></span>
<span id="index-fdiagnostics_002dshow_002dline_002dnumbers"></span>
</dd>
<dt><code>-fno-diagnostics-show-line-numbers</code></dt>
<dd><p>By default, when printing source code (via <samp>-fdiagnostics-show-caret</samp>),
a left margin is printed, showing line numbers.  This option suppresses this
left margin.
</p>
<span id="index-fdiagnostics_002dminimum_002dmargin_002dwidth"></span>
</dd>
<dt><code>-fdiagnostics-minimum-margin-width=<var>width</var></code></dt>
<dd><p>This option controls the minimum width of the left margin printed by
<samp>-fdiagnostics-show-line-numbers</samp>.  It defaults to 6.
</p>
<span id="index-fdiagnostics_002dparseable_002dfixits"></span>
</dd>
<dt><code>-fdiagnostics-parseable-fixits</code></dt>
<dd><p>Emit fix-it hints in a machine-parseable format, suitable for consumption
by IDEs.  For each fix-it, a line will be printed after the relevant
diagnostic, starting with the string &ldquo;fix-it:&rdquo;.  For example:
</p>
<div class="example">
<pre class="example">fix-it:&quot;test.c&quot;:{45:3-45:21}:&quot;gtk_widget_show_all&quot;
</pre></div>

<p>The location is expressed as a half-open range, expressed as a count of
bytes, starting at byte 1 for the initial column.  In the above example,
bytes 3 through 20 of line 45 of &ldquo;test.c&rdquo; are to be replaced with the
given string:
</p>
<div class="example">
<pre class="example">00000000011111111112222222222
12345678901234567890123456789
  gtk_widget_showall (dlg);
  ^^^^^^^^^^^^^^^^^^
  gtk_widget_show_all
</pre></div>

<p>The filename and replacement string escape backslash as &ldquo;\\&quot;, tab as &ldquo;\t&rdquo;,
newline as &ldquo;\n&rdquo;, double quotes as &ldquo;\&quot;&rdquo;, non-printable characters as octal
(e.g. vertical tab as &ldquo;\013&rdquo;).
</p>
<p>An empty replacement string indicates that the given range is to be removed.
An empty range (e.g. &ldquo;45:3-45:3&rdquo;) indicates that the string is to
be inserted at the given position.
</p>
<span id="index-fdiagnostics_002dgenerate_002dpatch"></span>
</dd>
<dt><code>-fdiagnostics-generate-patch</code></dt>
<dd><p>Print fix-it hints to stderr in unified diff format, after any diagnostics
are printed.  For example:
</p>
<div class="example">
<pre class="example">--- test.c
+++ test.c
@ -42,5 +42,5 @

 void show_cb(GtkDialog *dlg)
 {
-  gtk_widget_showall(dlg);
+  gtk_widget_show_all(dlg);
 }

</pre></div>

<p>The diff may or may not be colorized, following the same rules
as for diagnostics (see <samp>-fdiagnostics-color</samp>).
</p>
<span id="index-fdiagnostics_002dshow_002dtemplate_002dtree"></span>
</dd>
<dt><code>-fdiagnostics-show-template-tree</code></dt>
<dd>
<p>In the C++ frontend, when printing diagnostics showing mismatching
template types, such as:
</p>
<div class="example">
<pre class="example">  could not convert 'std::map&lt;int, std::vector&lt;double&gt; &gt;()'
    from 'map&lt;[...],vector&lt;double&gt;&gt;' to 'map&lt;[...],vector&lt;float&gt;&gt;
</pre></div>

<p>the <samp>-fdiagnostics-show-template-tree</samp> flag enables printing a
tree-like structure showing the common and differing parts of the types,
such as:
</p>
<div class="example">
<pre class="example">  map&lt;
    [...],
    vector&lt;
      [double != float]&gt;&gt;
</pre></div>

<p>The parts that differ are highlighted with color (&ldquo;double&rdquo; and
&ldquo;float&rdquo; in this case).
</p>
<span id="index-fno_002delide_002dtype"></span>
<span id="index-felide_002dtype"></span>
</dd>
<dt><code>-fno-elide-type</code></dt>
<dd><p>By default when the C++ frontend prints diagnostics showing mismatching
template types, common parts of the types are printed as &ldquo;[...]&rdquo; to
simplify the error message.  For example:
</p>
<div class="example">
<pre class="example">  could not convert 'std::map&lt;int, std::vector&lt;double&gt; &gt;()'
    from 'map&lt;[...],vector&lt;double&gt;&gt;' to 'map&lt;[...],vector&lt;float&gt;&gt;
</pre></div>

<p>Specifying the <samp>-fno-elide-type</samp> flag suppresses that behavior.
This flag also affects the output of the
<samp>-fdiagnostics-show-template-tree</samp> flag.
</p>
<span id="index-fdiagnostics_002dpath_002dformat"></span>
</dd>
<dt><code>-fdiagnostics-path-format=<var>KIND</var></code></dt>
<dd><p>Specify how to print paths of control-flow events for diagnostics that
have such a path associated with them.
</p>
<p><var>KIND</var> is &lsquo;<samp>none</samp>&rsquo;, &lsquo;<samp>separate-events</samp>&rsquo;, or &lsquo;<samp>inline-events</samp>&rsquo;,
the default.
</p>
<p>&lsquo;<samp>none</samp>&rsquo; means to not print diagnostic paths.
</p>
<p>&lsquo;<samp>separate-events</samp>&rsquo; means to print a separate &ldquo;note&rdquo; diagnostic for
each event within the diagnostic.  For example:
</p>
<div class="example">
<pre class="example">test.c:29:5: error: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter
test.c:25:10: note: (1) when 'PyList_New' fails, returning NULL
test.c:27:3: note: (2) when 'i &lt; count'
test.c:29:5: note: (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
</pre></div>

<p>&lsquo;<samp>inline-events</samp>&rsquo; means to print the events &ldquo;inline&rdquo; within the source
code.  This view attempts to consolidate the events into runs of
sufficiently-close events, printing them as labelled ranges within the source.
</p>
<p>For example, the same events as above might be printed as:
</p>
<div class="example">
<pre class="example">  'test': events 1-3
    |
    |   25 |   list = PyList_New(0);
    |      |          ^~~~~~~~~~~~~
    |      |          |
    |      |          (1) when 'PyList_New' fails, returning NULL
    |   26 |
    |   27 |   for (i = 0; i &lt; count; i++) {
    |      |   ~~~
    |      |   |
    |      |   (2) when 'i &lt; count'
    |   28 |     item = PyLong_FromLong(random());
    |   29 |     PyList_Append(list, item);
    |      |     ~~~~~~~~~~~~~~~~~~~~~~~~~
    |      |     |
    |      |     (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
    |
</pre></div>

<p>Interprocedural control flow is shown by grouping the events by stack frame,
and using indentation to show how stack frames are nested, pushed, and popped.
</p>
<p>For example:
</p>
<div class="example">
<pre class="example">  'test': events 1-2
    |
    |  133 | {
    |      | ^
    |      | |
    |      | (1) entering 'test'
    |  134 |   boxed_int *obj = make_boxed_int (i);
    |      |                    ~~~~~~~~~~~~~~~~~~
    |      |                    |
    |      |                    (2) calling 'make_boxed_int'
    |
    +--&gt; 'make_boxed_int': events 3-4
           |
           |  120 | {
           |      | ^
           |      | |
           |      | (3) entering 'make_boxed_int'
           |  121 |   boxed_int *result = (boxed_int *)wrapped_malloc (sizeof (boxed_int));
           |      |                                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           |      |                                    |
           |      |                                    (4) calling 'wrapped_malloc'
           |
           +--&gt; 'wrapped_malloc': events 5-6
                  |
                  |    7 | {
                  |      | ^
                  |      | |
                  |      | (5) entering 'wrapped_malloc'
                  |    8 |   return malloc (size);
                  |      |          ~~~~~~~~~~~~~
                  |      |          |
                  |      |          (6) calling 'malloc'
                  |
    &lt;-------------+
    |
 'test': event 7
    |
    |  138 |   free_boxed_int (obj);
    |      |   ^~~~~~~~~~~~~~~~~~~~
    |      |   |
    |      |   (7) calling 'free_boxed_int'
    |
(etc)
</pre></div>

<span id="index-fdiagnostics_002dshow_002dpath_002ddepths"></span>
</dd>
<dt><code>-fdiagnostics-show-path-depths</code></dt>
<dd><p>This option provides additional information when printing control-flow paths
associated with a diagnostic.
</p>
<p>If this is option is provided then the stack depth will be printed for
each run of events within <samp>-fdiagnostics-path-format=inline-events</samp>.
If provided with <samp>-fdiagnostics-path-format=separate-events</samp>, then
the stack depth and function declaration will be appended when printing
each event.
</p>
<p>This is intended for use by GCC developers and plugin developers when
debugging diagnostics that report interprocedural control flow.
</p>
<span id="index-fno_002dshow_002dcolumn"></span>
<span id="index-fshow_002dcolumn"></span>
</dd>
<dt><code>-fno-show-column</code></dt>
<dd><p>Do not print column numbers in diagnostics.  This may be necessary if
diagnostics are being scanned by a program that does not understand the
column numbers, such as <code>dejagnu</code>.
</p>
<span id="index-fdiagnostics_002dcolumn_002dunit"></span>
</dd>
<dt><code>-fdiagnostics-column-unit=<var>UNIT</var></code></dt>
<dd><p>Select the units for the column number.  This affects traditional diagnostics
(in the absence of <samp>-fno-show-column</samp>), as well as JSON format
diagnostics if requested.
</p>
<p>The default <var>UNIT</var>, &lsquo;<samp>display</samp>&rsquo;, considers the number of display
columns occupied by each character.  This may be larger than the number
of bytes required to encode the character, in the case of tab
characters, or it may be smaller, in the case of multibyte characters.
For example, the character &ldquo;GREEK SMALL LETTER PI (U+03C0)&rdquo; occupies one
display column, and its UTF-8 encoding requires two bytes; the character
&ldquo;SLIGHTLY SMILING FACE (U+1F642)&rdquo; occupies two display columns, and
its UTF-8 encoding requires four bytes.
</p>
<p>Setting <var>UNIT</var> to &lsquo;<samp>byte</samp>&rsquo; changes the column number to the raw byte
count in all cases, as was traditionally output by GCC prior to version 11.1.0.
</p>
<span id="index-fdiagnostics_002dcolumn_002dorigin"></span>
</dd>
<dt><code>-fdiagnostics-column-origin=<var>ORIGIN</var></code></dt>
<dd><p>Select the origin for column numbers, i.e. the column number assigned to the
first column.  The default value of 1 corresponds to traditional GCC
behavior and to the GNU style guide.  Some utilities may perform better with an
origin of 0; any non-negative value may be specified.
</p>
<span id="index-fdiagnostics_002descape_002dformat"></span>
</dd>
<dt><code>-fdiagnostics-escape-format=<var>FORMAT</var></code></dt>
<dd><p>When GCC prints pertinent source lines for a diagnostic it normally attempts
to print the source bytes directly.  However, some diagnostics relate to encoding
issues in the source file, such as malformed UTF-8, or issues with Unicode
normalization.  These diagnostics are flagged so that GCC will escape bytes
that are not printable ASCII when printing their pertinent source lines.
</p>
<p>This option controls how such bytes should be escaped.
</p>
<p>The default <var>FORMAT</var>, &lsquo;<samp>unicode</samp>&rsquo; displays Unicode characters that
are not printable ASCII in the form &lsquo;<samp>&lt;U+XXXX&gt;</samp>&rsquo;, and bytes that do not
correspond to a Unicode character validly-encoded in UTF-8-encoded will be
displayed as hexadecimal in the form &lsquo;<samp>&lt;XX&gt;</samp>&rsquo;.
</p>
<p>For example, a source line containing the string &lsquo;<samp>before</samp>&rsquo; followed by the
Unicode character U+03C0 (&ldquo;GREEK SMALL LETTER PI&rdquo;, with UTF-8 encoding
0xCF 0x80) followed by the byte 0xBF (a stray UTF-8 trailing byte), followed by
the string &lsquo;<samp>after</samp>&rsquo; will be printed for such a diagnostic as:
</p>
<div class="example">
<pre class="example"> before&lt;U+03C0&gt;&lt;BF&gt;after
</pre></div>

<p>Setting <var>FORMAT</var> to &lsquo;<samp>bytes</samp>&rsquo; will display all non-printable-ASCII bytes
in the form &lsquo;<samp>&lt;XX&gt;</samp>&rsquo;, thus showing the underlying encoding of non-ASCII
Unicode characters.  For the example above, the following will be printed:
</p>
<div class="example">
<pre class="example"> before&lt;CF&gt;&lt;80&gt;&lt;BF&gt;after
</pre></div>

<span id="index-fdiagnostics_002dformat"></span>
</dd>
<dt><code>-fdiagnostics-format=<var>FORMAT</var></code></dt>
<dd><p>Select a different format for printing diagnostics.
<var>FORMAT</var> is &lsquo;<samp>text</samp>&rsquo;, &lsquo;<samp>sarif-stderr</samp>&rsquo;, &lsquo;<samp>sarif-file</samp>&rsquo;,
&lsquo;<samp>json</samp>&rsquo;, &lsquo;<samp>json-stderr</samp>&rsquo;, or &lsquo;<samp>json-file</samp>&rsquo;.
</p>
<p>The default is &lsquo;<samp>text</samp>&rsquo;.
</p>
<p>The &lsquo;<samp>sarif-stderr</samp>&rsquo; and &lsquo;<samp>sarif-file</samp>&rsquo; formats both emit
diagnostics in SARIF Version 2.1.0 format, either to stderr, or to a file
named <samp><var>source</var>.sarif</samp>, respectively.
</p>
<p>The &lsquo;<samp>json</samp>&rsquo; format is a synonym for &lsquo;<samp>json-stderr</samp>&rsquo;.
The &lsquo;<samp>json-stderr</samp>&rsquo; and &lsquo;<samp>json-file</samp>&rsquo; formats are identical, apart from
where the JSON is emitted to - with the former, the JSON is emitted to stderr,
whereas with &lsquo;<samp>json-file</samp>&rsquo; it is written to <samp><var>source</var>.gcc.json</samp>.
</p>
<p>The emitted JSON consists of a top-level JSON array containing JSON objects
representing the diagnostics.  The JSON is emitted as one line, without
formatting; the examples below have been formatted for clarity.
</p>
<p>Diagnostics can have child diagnostics.  For example, this error and note:
</p>
<div class="example">
<pre class="example">misleading-indentation.c:15:3: warning: this 'if' clause does not
  guard... [-Wmisleading-indentation]
   15 |   if (flag)
      |   ^~
misleading-indentation.c:17:5: note: ...this statement, but the latter
  is misleadingly indented as if it were guarded by the 'if'
   17 |     y = 2;
      |     ^
</pre></div>

<p>might be printed in JSON form (after formatting) like this:
</p>
<div class="example">
<pre class="example">[
    {
        &quot;kind&quot;: &quot;warning&quot;,
        &quot;locations&quot;: [
            {
                &quot;caret&quot;: {
		    &quot;display-column&quot;: 3,
		    &quot;byte-column&quot;: 3,
                    &quot;column&quot;: 3,
                    &quot;file&quot;: &quot;misleading-indentation.c&quot;,
                    &quot;line&quot;: 15
                },
                &quot;finish&quot;: {
		    &quot;display-column&quot;: 4,
		    &quot;byte-column&quot;: 4,
                    &quot;column&quot;: 4,
                    &quot;file&quot;: &quot;misleading-indentation.c&quot;,
                    &quot;line&quot;: 15
                }
            }
        ],
        &quot;message&quot;: &quot;this \u2018if\u2019 clause does not guard...&quot;,
        &quot;option&quot;: &quot;-Wmisleading-indentation&quot;,
        &quot;option_url&quot;: &quot;https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wmisleading-indentation&quot;,
        &quot;children&quot;: [
            {
                &quot;kind&quot;: &quot;note&quot;,
                &quot;locations&quot;: [
                    {
                        &quot;caret&quot;: {
			    &quot;display-column&quot;: 5,
			    &quot;byte-column&quot;: 5,
                            &quot;column&quot;: 5,
                            &quot;file&quot;: &quot;misleading-indentation.c&quot;,
                            &quot;line&quot;: 17
                        }
                    }
                ],
                &quot;escape-source&quot;: false,
                &quot;message&quot;: &quot;...this statement, but the latter is &hellip;&quot;
            }
        ]
	&quot;escape-source&quot;: false,
	&quot;column-origin&quot;: 1,
    }
]
</pre></div>

<p>where the <code>note</code> is a child of the <code>warning</code>.
</p>
<p>A diagnostic has a <code>kind</code>.  If this is <code>warning</code>, then there is
an <code>option</code> key describing the command-line option controlling the
warning.
</p>
<p>A diagnostic can contain zero or more locations.  Each location has an
optional <code>label</code> string and up to three positions within it: a
<code>caret</code> position and optional <code>start</code> and <code>finish</code> positions.
A position is described by a <code>file</code> name, a <code>line</code> number, and
three numbers indicating a column position:
</p><ul>
<li> <code>display-column</code> counts display columns, accounting for tabs and
multibyte characters.

</li><li> <code>byte-column</code> counts raw bytes.

</li><li> <code>column</code> is equal to one of
the previous two, as dictated by the <samp>-fdiagnostics-column-unit</samp>
option.

</li></ul>
<p>All three columns are relative to the origin specified by
<samp>-fdiagnostics-column-origin</samp>, which is typically equal to 1 but may
be set, for instance, to 0 for compatibility with other utilities that
number columns from 0.  The column origin is recorded in the JSON output in
the <code>column-origin</code> tag.  In the remaining examples below, the extra
column number outputs have been omitted for brevity.
</p>
<p>For example, this error:
</p>
<div class="example">
<pre class="example">bad-binary-ops.c:64:23: error: invalid operands to binary + (have 'S' {aka
   'struct s'} and 'T' {aka 'struct t'})
   64 |   return callee_4a () + callee_4b ();
      |          ~~~~~~~~~~~~ ^ ~~~~~~~~~~~~
      |          |              |
      |          |              T {aka struct t}
      |          S {aka struct s}
</pre></div>

<p>has three locations.  Its primary location is at the &ldquo;+&rdquo; token at column
23.  It has two secondary locations, describing the left and right-hand sides
of the expression, which have labels.  It might be printed in JSON form as:
</p>
<div class="example">
<pre class="example">    {
        &quot;children&quot;: [],
        &quot;kind&quot;: &quot;error&quot;,
        &quot;locations&quot;: [
            {
                &quot;caret&quot;: {
                    &quot;column&quot;: 23, &quot;file&quot;: &quot;bad-binary-ops.c&quot;, &quot;line&quot;: 64
                }
            },
            {
                &quot;caret&quot;: {
                    &quot;column&quot;: 10, &quot;file&quot;: &quot;bad-binary-ops.c&quot;, &quot;line&quot;: 64
                },
                &quot;finish&quot;: {
                    &quot;column&quot;: 21, &quot;file&quot;: &quot;bad-binary-ops.c&quot;, &quot;line&quot;: 64
                },
                &quot;label&quot;: &quot;S {aka struct s}&quot;
            },
            {
                &quot;caret&quot;: {
                    &quot;column&quot;: 25, &quot;file&quot;: &quot;bad-binary-ops.c&quot;, &quot;line&quot;: 64
                },
                &quot;finish&quot;: {
                    &quot;column&quot;: 36, &quot;file&quot;: &quot;bad-binary-ops.c&quot;, &quot;line&quot;: 64
                },
                &quot;label&quot;: &quot;T {aka struct t}&quot;
            }
        ],
        &quot;escape-source&quot;: false,
        &quot;message&quot;: &quot;invalid operands to binary + &hellip;&quot;
    }
</pre></div>

<p>If a diagnostic contains fix-it hints, it has a <code>fixits</code> array,
consisting of half-open intervals, similar to the output of
<samp>-fdiagnostics-parseable-fixits</samp>.  For example, this diagnostic
with a replacement fix-it hint:
</p>
<div class="example">
<pre class="example">demo.c:8:15: error: 'struct s' has no member named 'colour'; did you
  mean 'color'?
    8 |   return ptr-&gt;colour;
      |               ^~~~~~
      |               color
</pre></div>

<p>might be printed in JSON form as:
</p>
<div class="example">
<pre class="example">    {
        &quot;children&quot;: [],
        &quot;fixits&quot;: [
            {
                &quot;next&quot;: {
                    &quot;column&quot;: 21,
                    &quot;file&quot;: &quot;demo.c&quot;,
                    &quot;line&quot;: 8
                },
                &quot;start&quot;: {
                    &quot;column&quot;: 15,
                    &quot;file&quot;: &quot;demo.c&quot;,
                    &quot;line&quot;: 8
                },
                &quot;string&quot;: &quot;color&quot;
            }
        ],
        &quot;kind&quot;: &quot;error&quot;,
        &quot;locations&quot;: [
            {
                &quot;caret&quot;: {
                    &quot;column&quot;: 15,
                    &quot;file&quot;: &quot;demo.c&quot;,
                    &quot;line&quot;: 8
                },
                &quot;finish&quot;: {
                    &quot;column&quot;: 20,
                    &quot;file&quot;: &quot;demo.c&quot;,
                    &quot;line&quot;: 8
                }
            }
        ],
        &quot;escape-source&quot;: false,
        &quot;message&quot;: &quot;\u2018struct s\u2019 has no member named &hellip;&quot;
    }
</pre></div>

<p>where the fix-it hint suggests replacing the text from <code>start</code> up
to but not including <code>next</code> with <code>string</code>&rsquo;s value.  Deletions
are expressed via an empty value for <code>string</code>, insertions by
having <code>start</code> equal <code>next</code>.
</p>
<p>If the diagnostic has a path of control-flow events associated with it,
it has a <code>path</code> array of objects representing the events.  Each
event object has a <code>description</code> string, a <code>location</code> object,
along with a <code>function</code> string and a <code>depth</code> number for
representing interprocedural paths.  The <code>function</code> represents the
current function at that event, and the <code>depth</code> represents the
stack depth relative to some baseline: the higher, the more frames are
within the stack.
</p>
<p>For example, the intraprocedural example shown for
<samp>-fdiagnostics-path-format=</samp> might have this JSON for its path:
</p>
<div class="example">
<pre class="example">    &quot;path&quot;: [
        {
            &quot;depth&quot;: 0,
            &quot;description&quot;: &quot;when 'PyList_New' fails, returning NULL&quot;,
            &quot;function&quot;: &quot;test&quot;,
            &quot;location&quot;: {
                &quot;column&quot;: 10,
                &quot;file&quot;: &quot;test.c&quot;,
                &quot;line&quot;: 25
            }
        },
        {
            &quot;depth&quot;: 0,
            &quot;description&quot;: &quot;when 'i &lt; count'&quot;,
            &quot;function&quot;: &quot;test&quot;,
            &quot;location&quot;: {
                &quot;column&quot;: 3,
                &quot;file&quot;: &quot;test.c&quot;,
                &quot;line&quot;: 27
            }
        },
        {
            &quot;depth&quot;: 0,
            &quot;description&quot;: &quot;when calling 'PyList_Append', passing NULL from (1) as argument 1&quot;,
            &quot;function&quot;: &quot;test&quot;,
            &quot;location&quot;: {
                &quot;column&quot;: 5,
                &quot;file&quot;: &quot;test.c&quot;,
                &quot;line&quot;: 29
            }
        }
    ]
</pre></div>

<p>Diagnostics have a boolean attribute <code>escape-source</code>, hinting whether
non-ASCII bytes should be escaped when printing the pertinent lines of
source code (<code>true</code> for diagnostics involving source encoding issues).
</p>
</dd>
</dl>

<hr>
<div class="header">
<p>
Next: <a href="Warning-Options.html" accesskey="n" rel="next">Warning Options</a>, Previous: <a href="Objective_002dC-and-Objective_002dC_002b_002b-Dialect-Options.html" accesskey="p" rel="prev">Objective-C and Objective-C++ Dialect Options</a>, Up: <a href="Invoking-GCC.html" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
